Skip to content

Apps contract 1: the portal, into device-trust - #1344

Merged
evanrbowers merged 17 commits into
device-trustfrom
apps-contract-1
Nov 17, 2026
Merged

evanrbowers merged 17 commits into
device-trustfrom
apps-contract-1

Conversation

@evanrbowers

Copy link
Copy Markdown
Contributor

Why

Solo deploys from device-trust in every repo. Desktop had no such branch, so the contract-1 portal was waiting on a merge into solo. device-trust is now cut from solo, and this brings in the portal's contract-1 work so that both the web portal (app.solo.remote.it) and the device packages' bundled portal can be built from it.

What

No new code. The three PRs already reviewed and merged into apps-contract-1:

Known gap

Six new strings are untranslated in de, es and ja.

🤖 Generated with Claude Code

Evan Bowers and others added 9 commits November 15, 2026 07:11
…sole UI, no console detection

The portal had a part of its own for one app: FIRST_PARTY_APPS = {console} (ConsoleApp: its icon, state words,
ai_commands label, host key, Open terminal) and a console service found by type 28 at host remoteit-console
(sshHelper isConsoleService, in the services' rows, the connect panel and the device's name on this machine). An app
anyone ships could have none of it (presence-contract docs/self-contained-apps.md, the portal's row and
"Capabilities, as the platform keeps them"). Now every app is drawn from DeviceApp, CatalogApp and
CatalogAppRelease alone:

- protocol, capabilities, hostKey, sessions and sessionsOpen are read with an app; protocol and capabilities with
  a catalogue entry and each release (and a product's app, where the schema has them).
- An app whose service is ssh and that declares person-certificates (sshHelper opensTerminal) opens in web SSH,
  with the person's own account, a certificate and its host key checked: Open terminal in the Apps section and on
  its page, the terminal button in its device's services and the option in its connect panel (AppTerminal, which
  replaces ConsoleTerminal), the plain ssh command and its hint by name. Its service is the one its app names
  (DeviceApp.serviceId), or — disabled, naming none — the one at its app host (remoteit-app-<publisher>-<app>);
  a device's apps are read only for a service at an app host.
- The app's page says its state in the shared words, its settings in its release's labels and help (ai_commands
  included), the key its service presents where the device reports one, and the sessions it serves: how many, and
  who, as whom, by an AI and since when for those who manage it. Its icon comes from its protocol.
- What an app asks of remote.it beyond running is said in words beside Runs as root wherever it is offered — the
  catalogue, the device's catalogue (from its catalogue entry), the app and its releases, a product's apps — and is
  part of every root consent (the device's, the product's, Add's): "Keeps accounts for the people you share with",
  "Signs in people by remote.it certificate", "AI commands go through this app".
- This device's Advanced titles an app's on/off and its settings by the API's name and labels (the device by its
  UID), puts any app's settings under its row, and says "Not served" for an app that serves a service; only the
  device's own settings keep words here.

Until the console declares these (step 3) and its services move to its app host (step 4),
services/consoleUntilDeclared takes the console with no capabilities as declaring ssh, person-accounts,
person-certificates and ssh-exec, and its host remoteit-console as its app host, so it works as before. It is the
only place the portal names the console, and the removal step deletes it with its two calls. SCREENVIEW stays for
ScreenView's old install alone.

Needs graphql's DeviceApp.protocol/capabilities/hostKey/sessions/sessionsOpen and CatalogApp(Release)
.capabilities/protocol: an older graphql refuses these queries.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
…, opened by protocol, sessions by id

The portal reads what graphql says of an app under remoteit/apps contract 1, and names no app:

- Choices are {value, label}: the label shown, the value set; the manifest's string shorthand (or a choice without
  a label) is labelled by its value (deviceAppsShared choiceOf), for device and product settings alike.
- DeviceApp.portSetting: the setting that is the service's port is edited under Service ("Port people connect to")
  and not again under Settings; while the app is disabled, its service stopped, it stays under Settings.
- Opened by protocol: a page for http/https ("Open page"), a viewer for vnc/rdp ("Open screen", their icon), a
  terminal for ssh with person-certificates; the connection is the service's, whose type graphql makes from it.
- Sessions are the app's status.json: {session, login, via, since}, shown by the session id, never a person.
- DeviceApp.contract and .features are read; AvailableApp carries protocol/capabilities/contract itself, so the
  device's catalogue no longer reads the account's catalogue to describe its offers.
- CatalogApp drops kind and serves (contract 1 has run and listen, the daemon's to read); "stopped while
  disabled" is said where the release names a protocol.
- The temporary console fallback (consoleUntilDeclared) is gone: graphql names no app and serves the console at
  its app host.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
…ing version's

A consent covers the release it moves the device (or product) to — a pin, Update now's waiting release, the release
enabling gives — and that release may ask more of remote.it than the version running. Every RootConsent now names the
capabilities of that release (`release`), read from its catalogue entry (useReleaseAsks), and its yes waits until they
are read; where no release is named, or the catalogue cannot say, the app's own are named (graphql still refuses a yes
that does not cover what the release asks). useAppSwitch passes the release it consents to and the device's account;
the pin's consent and a product's consent pass theirs.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Device apps (portal): contract 1 — every app from the API, labelled choices, the owner's port, opened by protocol
… udp service is a connection alone

A setting the device's administrator holds (DeviceAppSetting.control off, on —
where its release says forcible, as the console's "Allow AI commands" — or a choice
it fixes) is shown at the held value, greyed, "Set by this device's administrator",
with its product's lock beside it where the product holds it too. graphql refuses a
change to it, so none is offered.

A service whose protocol is udp has nothing to launch and no terminal or page: its
Open is Connect, which connects without launching, and its line says UDP port, the
port for the person's own UDP client.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Device apps (portal): a setting its administrator holds is said so; a udp service is a connection alone
…pened on its own

An app may now have several services, and a service several ports (its
listeners' own, the first its launch port). The portal read one service per app
(DeviceApp.serviceId, protocol, portSetting); it now reads DeviceApp.services,
the primary first, and DeviceApp.listeners.

- The app's page shows each served service: its name and port, or a multi-port
  one's ports as a list with the existing multi-port words — a connection
  reaches the first, the rest by name on the device subnet. Each has its own
  Open (Connect for udp, launching nothing) or Open terminal.
- A setting that is a service's port, or one of its listeners', is edited under
  that service, labelled with it ("Port people connect to", "Port of rtsp"),
  and not again under Settings; under Settings while its service is stopped.
- A device's service is its app's when the app names it among its services
  (serviceApp, appServiceOf); web SSH asks the service's own protocol.
- AvailableApp reads services too, so an offered app's primary is known.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
…their ports are graphql's

A change to a service's or a listener's port setting moves the service's ports, which
graphql keeps in step; the page showed the ports it read before until a reload. The
apps are read again after one, and a service's ports are graphql's, else its device
service's.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Device apps (portal): every service of an app, each with its ports, opened on its own
@evanrbowers

Copy link
Copy Markdown
Contributor Author

@codex review

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Nov 17, 2026 •

Copy link
Copy Markdown
Codex Review Summary: ✅ Completed

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-11-17T19:54:05.524427Z 6c23c18 Manual request
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 09fde4b9bb

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread frontend/src/hooks/useDeviceApps.ts Outdated
Comment on lines +140 to +142
if (isPortSetting(app, name)) {
const read = await graphQLDeviceApps(deviceId)
if (read) tell(deviceId, read)

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Refresh the device's service data after changing an app port

When an SSH app's port setting changes, this refresh updates only the useDeviceApps subscribers, leaving DeviceContext.device.services unchanged. AppTerminalAction still obtains its launch port from that separate service list (AppTerminal.tsx, lines 33–45), rather than the refreshed DeviceAppService.ports. Consequently, the app page can display the new port while Open terminal connects to the old one until an independent device refresh occurs. Refresh the device's service data as well, or use the refreshed app service's first port when opening the terminal.

Useful? React with 👍 / 👎.

Comment thread frontend/src/pages/AppAddDialog.tsx Outdated
const standing = ready?.releases.filter(r => !r.withdrawn) ?? []
const pinned = pinning && version ? standing.find(r => r.version === version) : undefined
const root = pinned ? pinned.root : !!ready?.root
const capabilities = pinned ? pinned.capabilities : ready?.capabilities

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Derive capability disclosures from the selected channel

When someone selects a channel different from the account's default without pinning a version, the add mutation receives that selected channel, but this capability list still comes from ready.capabilities, which describes the account's default-channel release (CatalogApp.version). For example, if stable requests no capabilities and beta adds ssh-exec, choosing beta never discloses that AI commands will go through the app, including in the root-consent section. Resolve the selected channel's release before choosing its capabilities, and invalidate any existing consent when that selection changes.

Useful? React with 👍 / 👎.

evanrbowers and others added 2 commits November 17, 2026 11:06
…'s ports are the device's

An app's services are its device's services, and every part of the portal that
connects to one (its row's terminal button, its connect panel, Open, Open
terminal on the Apps section and the app's page) reads where it listens from
the device in the store. A port setting moved the port in graphql, and only the
apps were read again: the app's page showed the new port while Open terminal
connected to the old one until some other device refresh.

useDeviceApps now reads the device again (devices.fetchSingleFull, under the
device's account) after a port setting and after any app change that went
through, since enabling, disabling, removing or moving an app to another
release can add, remove or move its services with no event saying so while the
service stays online. The app's page reads its services' ports from the device
too, so DeviceAppService.ports, a second copy of the same fact, is no longer
asked for.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
…nly for that choice

The Add dialog sent the channel chosen but disclosed what the account's channel's
release asks (CatalogApp.root and capabilities), so choosing beta where beta's
release asks ssh-exec, or runs as root, never said so. addAsks (appsHelper)
resolves the releases an add gives as graphql does (releaseFor, channelVersion):
the pin; else the chosen channel's, the account's where none is: its candidate
to the devices in its share and its current to the rest, a channel naming none
giving stable's, a withdrawn release none. Root and capabilities are what those
releases ask together, each as CatalogApp.releases lists it; one not among the
releases read asks what the app's own fields say, graphql refusing an add whose
consent does not cover its release.

The yes is kept with what it was given for (target, product, releases): another
channel, pin, target or product asks it again.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Apps contract 1: device re-read after app changes; Add discloses the chosen channel's release
@evanrbowers

Copy link
Copy Markdown
Contributor Author

@codex review

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 01831f0ac1

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

product
app={asking}
version={asking?.state === 'enabled' && asking.needsConsent ? asking.awaitingRoot : undefined}
release={asking?.awaitingRoot || asking?.version}

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Pass the product's account into the release-consent lookup

When reviewing a private organization's app update on the product policy page, this consent dialog does not receive accountId, although useProductPolicy reads the product under the active account. Consequently, useReleaseAsks calls graphQLCatalogApp without the organization account, so an organization-only app cannot be resolved and the dialog falls back to asking.capabilities. For an update awaiting root consent, those capabilities describe the release currently given to devices, not necessarily awaitingRoot, so newly requested capabilities can be omitted before consent enables the update across the product. Pass the product's account through to RootConsent, as the device-app callers already do.

Useful? React with 👍 / 👎.

…ount the device or product was read for

graphql asks consentRoot of any release that runs as root or declares
capabilities (app-catalog.ts consentAsked/asksConsent), unless a consent kept
covers it (coversRootAmong). The portal asked only for root releases, so a
restricted app declaring person-certificates or ssh-exec was enabled, added,
pinned or moved without the yes, and graphql refused it.

One rule now, in helpers/appsHelper: consentAsked/asksConsent, and
consentCovers (coversRootAmong, over the catalogue's releases, newest first).
Every place the portal decides uses it:
- useAppSwitch (Apps section, app page, connect panel, device catalogue): asks
  where graphql names a release awaiting consent (awaitingRoot, enabled or not),
  or for an app not on the device yet whose release asks.
- The app page's channel, pin and Unpin: the releases the change gives
  (addAsks), asked first where one asks and the kept consent does not cover it,
  while the app is enabled.
- Add an app (devices, tag, product) and the fleet's Pin and Update.
- Product policy: needsConsent, or, turning one on, the release the product
  names (productRelease) read from the catalogue and weighed against the
  product's consent.

The words say what is asked: root's full control where the release runs as
root, else what it asks of remote.it, with its capabilities either way. Lines
that said "needs to run as root" for any consent say so only where graphql's
words or the catalogue say root.

The release-consent lookup names the account the device or product was read
under: RootConsent, useReleaseAsks and useAppSwitch take accountId as a required
argument, and the product policy page passes the account useProductPolicy read
the product under, which it omitted.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
evanrbowers and others added 4 commits November 17, 2026 11:32
…give

A channel rolling out a candidate gives a device its candidate or its current,
by the device's bucket, which is graphql's to compute. The app page's channel
change asked for one of them (the root one, where one was), so a candidate
declaring a capability the current does not was consented to without being
named. RootConsent and useReleaseAsks now take several releases and say what
they ask together; the channel, pin and Unpin changes name every release they
may give that asks for a consent the kept one does not cover.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
…ves to asks

Update selected unpins the devices (version ""), moving each to the release its
channel gives it (latest). Its consent named the pinned release's capabilities,
and asked only for devices held for consent: a device pinned elsewhere was moved
to a release asking more without the yes, and graphql refused it. It now asks
where a device is held for consent or would move off a pin to a release that
asks, and names what those latest releases ask together (root as graphql's
held-back words say where the catalogue does not list one).

The tests no longer change the shared catalogue fixture's releases in place.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
…and no yes is taken for it

Where the catalogue did not answer for the release a consent was for (an API
without one, an error, a release older than those read), the portal showed the
app's own fields instead: the release it runs, not the one the yes moves it to.
A restricted app held for a root release was then asked as restricted, and the
yes still authorized root.

What a named release asks is now known or not: useReleaseAsks answers null for
one the catalogue does not list, and RootConsent says so ("What this version
asks could not be read …"), words for root, and keeps the yes. addAsks says
known: false for a release not read and the Add dialog waits; the fleet's
Update waits likewise; the app page's channel and pin ask for a release not
read rather than skipping it. The app's own fields are used only where they are
the release in question: an app offered to the device, whose fields are what
its release asks there. useAppSwitch names awaitingRoot alone, as graphql's
DeviceApp capabilities describe the release given, not the one awaited.

The device app page and the Add dialog read the newest 100 releases, as the
consent lookup does.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Apps contract 1: consent asked exactly as graphql asks it, under the device's or product's account
@evanrbowers

Copy link
Copy Markdown
Contributor Author

@codex review

@chatgpt-codex-connector

Copy link
Copy Markdown

Codex Review: Didn't find any major issues. Bravo.

Reviewed commit: 6c23c186cd

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

@evanrbowers
evanrbowers merged commit 20f57b1 into device-trust Nov 17, 2026
2 checks passed
@evanrbowers
evanrbowers deleted the apps-contract-1 branch November 17, 2026 19:54
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant